Games of Daze

home *** CD-ROM | disk | FTP | other *** search

/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / djgpp / tktdoc / socklib.doc < prev next >

Wrap

Text File | 1994-08-11 | 27.7 KB | 1,143 lines

THE BERKELEY SOCKET LIBRARY In order for applications to communicate with each other, whether on the same machine or different machines across a network, the Berkeley Socket Interface was chosen as the means to accomplish this in the DESQview/X environment. The reasons for this are clear. The Berkeley Socket Interface is the standard which other X Window systems and UNIX systems use to communicate. In addition, it is network independent--in fact, a network need not be present on a standalone system. DESQview/X uses the Berkeley Socket Interface 4.3, or BSD 4.3. This release includes two different types of communication--stream (TCP) and datagram (UDP). DESQview/X, through its BSD 4.3 routines, supports both of these types. DESQview/X supplies both the include files necessary to compile an application that uses BSD 4.3 as well as a socket library that performs the low level functions. The include files needed are specified in each function's synopsis. The socket library is included in the DESQview/X System Library (sys.lib) which should be linked into your application. Since the Berkeley Socket Interface is a well-defined (and expansive) interface, this document does not attempt to teach a user how to use BSD 4.3 Sockets--there is plenty of material that does this already. See Chapter 1: Introduction for additional information. Instead, each of the BSD 4.3 Socket routines that are supported in DESQview/X will now be listed in reference form. Supported BSD 4.3 Socket Routines gethostbyaddr SYNOPSIS #include <sys/types.h> #include <sys/socket.h> #include <netdb.h> struct hostent *gethostbyaddr(char *addr,int addrLen,int af); DESCRIPTION Searches the local HOSTS file sequentially until an entry is found with an h_addr_list entry corresponding to the address pointed to by the 'addr' parameter. Return Values gethostbyaddr returns NULL on failure. Notes The hostent structure is defined in the description of the gethostent call. See Also sethostent, gethostent, gethostbyname, endhostent gethostbyname SYNOPSIS #include <sys/types.h> #include <sys/socket.h> #include <netdb.h> struct hostent *gethostbyname(char *name); DESCRIPTION Searches the local HOSTS file sequentially until an entry is found with an h_name that corresponds to the 'name' parameter. Return Values gethostbyname returns NULL on failure. See Also sethostent, gethostent, gethostbyaddr, endhostent gethostname SYNOPSIS #include <sys/types.h> #include <sys/socket.h> #include <netdb.h> int gethostname(char *name,int nameLen); DESCRIPTION gethostname retrieves the name of the local host. The 'name' parameter is a buffer of maximum size designated by the 'nameLen' parameter. The buffer will be filled with a null-terminated string unless insufficient space is available. Return Values gethostname returns bytes filled on success, -1 on failure. setservent SYNOPSIS #include <netdb.h> void setservent(int stayopen); DESCRIPTION setservent opens and rewinds the local SERVICES file. This call is primarily useful for resetting the SERVICES file to the first entry in preparation for calls to getservent. The stayopen parameter is currently ignored. See Also endservent, getservent, getservbyport, getservbyname getservent SYNOPSIS #include <netdb.h> struct servent *getservent(void); DESCRIPTION getservent reads the next entry in the local SERVICES file, opening the file if necessary. The return value is a pointer to a structure containing the broken-out fields of a line from the SERVICES file. The structure definition is as follows: struct servent { char *s_name; char **s_aliases; int s_port; char *s_proto; }; s_name, The official name of the service. s_aliases A NULL terminated list of alternate names for the service. s_port, The port number which the service uses. Port numbers are returned in network short byte order. s_proto The name of the protocol to use when contacting the service. Return Values getservent returns NULL on failure or EOF. See Also setservent, getservbyname, getservbyport, endservent endservent SYNOPSIS #include <netdb.h> void endservent(void); DESCRIPTION endservent closes the local SERVICES file. See Also setservent, getservent, getservbyport, getservbyname getservbyname SYNOPSIS #include <netdb.h> struct servent *getservbyname(char *name,char *proto); DESCRIPTION getservbyname searches the local SERVICES file sequentially until an entry with the s_name field matching the 'name' parameter is found. If a non-NULL 'proto' parameter is specified, the search will also include a match of the s_proto field with the 'proto' parameter. Notes The servent structure is defined in the description of the getservent call. Return Values getservbyname returns NULL on failure. See Also setservent, getservent, getservbyport, endservent getservbyport SYNOPSIS #include <netdb.h> struct servent *getservbyport(int port,char *proto); DESCRIPTION getservbyport searches the local SERVICES file sequentially until an entry with an s_port matching the 'port' parameter is found. If a non-NULL 'proto' parameter is specified, the search will also include a match of the s_proto field with the 'proto' parameter. Notes The servent structure is defined in the description of the getservent call. Return Values getservbyport returns NULL on failure. See Also setservent, getservent, getservbyname, endservent getprotobyname SYNOPSIS #include <netdb.h> struct protoent *getprotobyname(char *name); DESCRIPTION getprotobyname searches the local PROTOCOLS file sequentially until an entry is found with a p_name that matches the 'name' parameter. Notes The protoent structure is defined in the description of the getprotoent call. Return Values getprotobyname returns NULL on failure. See Also getprotobynumber getprotobynumber SYNOPSIS #include <netdb.h> struct protoent *getprotobynumber(int proto); DESCRIPTION getprotobynumber searches the local PROTOCOLS file sequentially until an entry is found with a p_proto that matches the 'proto' parameter. Notes The protoent structure is defined in the description of the getprotoent call. Return Values getprotobynumber returns NULL on failure. See Also getprotobyname socket SYNOPSIS #include <sys/types.h> #include <sys/socket.h> int socket(int af,int type,int protocol); DESCRIPTION socket opens an endpoint for network communication. The af parameter specifies the address family desired for the socket. The following address families are supported: AF_INET, Internet addressing family AF_UNIX, Local (file-type) addressing family The 'type' parameter specifies the method of I/O that will be available to the socket. SOCK_STREAM and SOCK_DGRAM are supported. SOCK_STREAM type sockets provide connection oriented, stream communications. Similar to pipes, full duplex, reliable and sequenced delivery is guaranteed. In order for I/O to occur, the socket must be in a connected state. Data transfer is accomplished by way of the recv and send calls, and both blocking and non-blocking modes are supported. SOCK_DGRAM type sockets provide connectionless, datagram (fixed length) communications. There is no guarantee of reliablity or sequencing. SOCK_DGRAM sockets need not be in a connected state in order to transmit or receive data. Data transfer is accomplished by way of the recvfrom and sendto calls, and both blocking and non-blocking modes are supported. The 'protocol' parameter is ignored at this time. Return Values socket returns a non-negative descriptor on success, -1 on failure (errno as described below). Errors EAFNOSUPPORT, The address family specified is not supported. EPROTOTYPE, The protocol specified is not supported. ESOCKTNOSUPPORT, The type specified is not SOCK_STREAM or SOCK_DGRAM ENOBUFS, The network has exhausted its resources. See Also accept, bind, connect, getsockname, ioctl, listen, recv, select, send, so_close so_close SYNOPSIS #include <sys/types.h> #include <sys/socket.h> int so_close(int s); DESCRIPTION Closes and frees the socket descriptor referenced by 's'. If the socket is of type SOCK_STREAM and in a connected state, the connection is closed, and the remote peer is notified. If the socket is of type SOCK_STREAM and in a listening state, any connections available for acceptance will be lost. Return Values so_close returns 0 on success, -1 on failure (errno as described below). Errors ENOTSOCK, The specified descriptor was invalid. bind SYNOPSIS #include <sys/types.h> #include <sys/socket.h> int bind(int s,struct sockaddr *addr,int addrLen); DESCRIPTION Assigns a name to the unnamed socket referenced by 's'. The name bound to the socket is specified by the 'addr' parameter. Return Values bind returns 0 on success, -1 on failure (errno as described below). Errors ENOTSOCK, Invalid descriptor. EAFNOSUPPORT, Invalid address family. EINVAL, Socket is already bound. EADDRINUSE, A socket is already bound to the address on the local host. getsockname SYNOPSIS #include <sys/types.h> #include <sys\socket.h> int getsockname(int s,struct sockaddr *name,int *nameLen); DESCRIPTION getsockname returns the name associated with socket s, assigned by a previous call to bind. The value pointed to by namelen should be initialized to the size of the buffer pointed to by 'name'. The name of the socket will be placed into the buffer pointed to by the 'name' parameter and the value pointed to by the 'namelen' parameter will be updated to the actual size of the name returned. Return Values getsockname returns 0 on success, -1 on failure (errno as described below). Errors ENOTSOCK, Invalid descriptor. EINVAL, Socket is not bound. ioctl SYNOPSIS #include <sys/types.h> #include <sys\socket.h> int ioctl(int s,int req,long *argp); DESCRIPTION Modifies the I/O strategy on the socket specified by 's' to the strategy indicated by 'req' and value specified by 'argp'. For example, modification of a socket to a non-blocking I/O strategy would entail a call as follows: nonBlocking = 1l; ioctl(s, FIONBIO, (long *)&nonBlocking); Return Values ioctl returns 0 on most requests, but may return non-zero values on success for some operations. On failure, ioctl returns -1 and errno is set as described below. Errors ENOTSOCK, Invalid descriptor. EINVAL, Invalid option specified. select SYNOPSIS #include <sys/types.h> #include <sys/time.h> int select(int nfds,struct fd_set *readfds, struct fd_set *writefds,struct fd_set *exceptfds, struct timeval *timeout); DESCRIPTION The select call examines the bitmasks pointed to by 'readfds', 'writefds' and 'exceptfds' and determines the readability and writeability of the sockets specified by the bits in the masks. Each bit position in the input mask designates the integer value of the socket desired for evaluation. The 'nfds' parameter indicates the range of selectors to be examined. The 'timeout' parameter is a pointer to a structure indicating the time to wait (block) for the selection to complete. A NULL timeout pointer indicates that the operation should block indefinitely until the select completes. A poll operation can be undertaken by passing a pointer to a timeval structure intialized to zero. Although the primary uses of select include determining whether a descriptor is readable or writeable, it can also indicate several conditions. A select can be undertaken on a SOCK_STREAM socket in a listening state to determine whether a connection is available for acceptance. This test is performed by setting the bit corresponding to the socket in the read mask, and determining whether it remains set following the call. An accept call can then be issued to retrieve the pending connection. Additionally, select can indicate a dropped connection on a SOCK_STREAM socket in a connected state. This check is performed in a manner similar to that for a listening socket (described above). An immediate recv operation can then be performed to either retrieve pending data or determine the cause of the failure. Return Values On success, select returns a non-negative indicator of the number of descriptors successfully examined. A 0 is returned if a timeout occured. On failure, select returns -1 and errno is set as described below. Errors EBADF, One of the descriptors specified in the bitmasks is invalid. setsockopt SYNOPSIS #include <sys/types.h> #include <sys/socket.h> int setsockopt(int s,int level,int name,char *val,int len); DESCRIPTION This call provided for compatibility only. accept SYNOPSIS #include <sys/types.h> #include <sys/socket.h> int accept(int s,struct sockaddr *addr,int *addrLen); DESCRIPTION accept examines the listening socket designated by 's' for pending connections. The socket must be of type SOCK_STREAM created by a socket call, bound to an address with bind and is listening for connections after a listen call. If a connection is available, accept creates a new socket with the properties of s and returns it to the caller as the connected socket. The socket designated by 's' is still available to accept further connections. If no connections are available, and the socket is marked as non-blocking, an error is returned as described below. If the socket is marked as blocking, the call blocks until a connection is available. When a valid connection descriptor is returned, the 'addr' parameter is filled with the address of the connection partner, up to a length specified by the value pointed to by 'addrLen'. The value pointed to by 'addrLen' is then updated to reflect the actual size of the address. Return Values Like socket, accept returns a non-negative descriptor on success. On failure, it returns -1 and sets errno as described below. Errors ENOTSOCK, Invalid descriptor. EWOULDBLOCK, No connections pending. See Also accept, socket connect SYNOPSIS #include <sys/types.h> #include <sys/socket.h> int connect(int s,struct sockaddr *name,int nameLen); DESCRIPTION For SOCK_STREAM type sockets, connect attempts to establish a connection between the socket specified by 's' and opened with a socket call and a destination socket opened with socket, bound to the destination address specified by 'name' and listening for connection requests. A SOCK_STREAM socket can only be connected once. For SOCK_DGRAM type sockets, connect specifies the destination to be used for send requests and the only peer from which datagrams can be received. Provided for convenience, this allows datagram sockets to use the recv and send calls in addition to recvfrom and sendto. SOCK_DGRAM sockets can connect multiple times and can dissolve the current connection by making a call to connect with a NULL destination name. Return Values connect returns 0 on success, -1 on failure (errno set as described below). Errors ENOTSOCK, Invalid descriptor. EAFNOSUPPORT, Invalid address family. EISCONN, Socket is already connected. EWOULDBLOCK, Processing connect request. ECONNREFUSED, Connection refused. EINPROGRESS, Processing connect request. ETIMEDOUT, Connection establishment timed out without establishing a connection. See Also socket, accept, listen, select listen SYNOPSIS #include <sys/types.h> #include <sys/socket.h> int listen(int s,int backlog); DESCRIPTION listen prepares the SOCK_STREAM socket specified by 's', created by a socket call and bound to an address with bind, to accept connections made by other SOCK_STREAM sockets calls to connect. The connection status of the socket may be queried by calls to select, and new connections are retrieved by calls to accept. The 'backlog' parameter indicates the number of simultaneous pending connections that can be queued between accept calls. Return Values listen returns 0 on success, -1 on failure (errno set as described below). Errors ENOTSOCK, Invalid descriptor. ECONNREFUSED, Socket not bound or non-stream. ENOBUFFS, Insufficient resources. See Also socket, accept, select, connect recv SYNOPSIS #include <sys/types.h> #include <sys/socket.h> int recv(int s,char *buffer,int buffLen,int flags); DESCRIPTION recv is used to receive data for a connected socket from its connection peer. The 'buffer' parameter is filled up to a maximum of 'buffLen' bytes. If the socket is marked as blocking, the recv call waits until data is available on the connection. If the socket is marked as non-blocking the call returns immediately with an error code if no data is available. This call can be made after a call to select() to determine the readability of the socket. Notes The 'flags' parameter is ignored. Return Values On success, recv returns a non-negative integer indicating the length of the data returned in the 'buffer' parameter. On connection termination, recv returns 0. On errors, recv returns -1 and errno as described below. Errors ENOTCONN, Connection terminated. ENOTSOCK, Invalid descriptor or connection failure. EWOULDBLOCK, No data available. ESHUTDOWN, Socket shutdown. See Also send, sendto, recvfro send SYNOPSIS #include <sys/types.h> #include <sys/socket.h> int send(int s,const char *buffer,int buffLen,int flags); DESCRIPTION send is used to transmit data for a connected socket to its connection peer. A maximum number of bytes will be sent corresponding to the 'buffLen' parameter. If the socket is marked as blocking, the send call will wait until all data has been sent on the connection. If the socket is marked as non-blocking, the call returns immediately with an error code if no data was sent. This call can be made after a call to select() to determine the writeability of the socket. Notes The 'flags' parameter is ignored. Return Values On success, send returns a non-negative integer indicating the number of bytes transmitted. On failure, -1 is returned with errno as described below. Errors ENOTSOCK, Invalid descriptor EWOULDBLOCK, No send buffer space available. ENOTCONN, Connection terminated. ESHUTDOWN, Socket shutdown. See Also sendto, recv, recvfrom getpeername SYNOPSIS #include <sys/types.h> #include <sys/socket.h> int getpeername(int s,struct sockaddr *name, int *nameLen); DESCRIPTION Retrieves the name of the remote peer connected to the socket specified by 's'. The 'nameLen' parameter is initialized to the maximum space available in the 'name' parameter, and is updated to reflect the actual length of the name placed into the 'name' parameter. Return Values getpeername returns 0 on success, -1 on failure (errno as described below). Errors ENOTSOCK, Invalid descriptor. ENOTCONN, Socket is not connected. recvfrom SYNOPSIS #include <sys/types.h> #include <sys/socket.h> int recvfrom(int s, char **buffer, int len, int flags, struct sockaddr *from, int flen); DESCRIPTION recvfrom is used to receive data for the connected, SOCK_STREAM type socket or for the SOCK_DGRAM socket specified by 's'.This call is identical to the recv call with the addition that the 'from' parameter is filled with the name of the socket sending the data. The 'flen' parameter is initialized to the maximum size of the buffer pointed to by from and updated to the actual length of the name placed into the from buffer. Notes The 'flags' parameter is ignored. Return Values On success, recv returns a non-negative integer indicating the length of the data returned in the 'buffer' parameter. On connection termination, recv returns 0. On errors, recv returns -1 and errno as described below. Errors ENOTCONN, Connection terminated. ENOTSOCK, Invalid descriptor or connection failure. EWOULDBLOCK, No data available. ESHUTDOWN, Socket shutdown. See Also send, sendto, recv sendto SYNOPSIS #include <sys/types.h> #include <sys/socket.h> int sendto(int s, const char *buffer, int len, intflags, struct sockaddr *to, int tolen); DESCRIPTION sendto is used to transmit data for the connected, SOCK_STREAM type socket or for the SOCK_DGRAM socket specified by 's'.This call is identical to the send call with the addition that the 'to' parameter indicates the name of the destination socket for SOCK_DGRAM sockets and is ignored for SOCK_STREAM sockets. The 'tolen' parameter is set to the size of the buffer to be sent. Notes The 'flags' parameter is ignored. Return Values On success, send returns a non-negative integer indicating the number of bytes transmitted. On failure, -1 is returned with errno as described below. Errors ENOTSOCK, Invalid descriptor EWOULDBLOCK, No send buffer space available. ENOTCONN, Connection terminated. ESHUTDOWN, Socket shutdown. See Also send, recv, recvfrom htonl SYNOPSIS #include <sys/types.h> #include <netinet/in.h> unsigned long htonl(unsigned long ibmdd); /* host to network long */ unsigned int htons(unsigned int ibmdw); /* host to network short */ unsigned long ntohl(unsigned long netdd); /* network to host long */ unsigned int ntohs(unsigned int netdw); /* network to host short */ DESCRIPTION These routines convert 16 and 32 bit quantities between 80x86 byte ordering and network byte ordering, and vice-versa. They are most often used in combination with the SERVICES routines and Internet address routines. inet_addr SYNOPSIS #include <sys/types.h> #include <sys/socket.h> #include <netinet/in.h> #include <arpa/inet.h> unsigned long inet_addr(const char *addrDesc); DESCRIPTION inet_addr returns the network long integer representation of the Internet '.' notation ASCIIZ string specified by 'addrDesc'. Return Values inet_addr -1 on invalid input string. inet_lnaof SYNOPSIS #include <sys/types.h> #include <sys/socket.h> #include <netinet/in.h> #include <arpa/inet.h> unsigned long inet_lnaof(struct in_addr); DESCRIPTION Returns the network byte order long integer value representing the local address portion of the Internet address specified by 'addr'. inet_makeaddr SYNOPSIS #include <sys/types.h> #include <sys/socket.h> #include <netinet/in.h> #include <arpa/inet.h> long inet_makeaddr(long net, long lna); DESCRIPTION Combines the network and local address portions specified in network byte order into a single Internet address. inet_netof SYNOPSIS #include <sys/types.h> #include <sys/socket.h> #include <netinet/in.h> #include <arpa/inet.h> ulong inet_netof(struct in_addr); DESCRIPTION Returns the network byte order long integer value representing the network portion of the Internet address specified by 'addr'. inet_network SYNOPSIS #include <sys/types.h> #include <sys/socket.h> #include <netinet/in.h> #include <arpa/inet.h> unsigned long inet_network(const char *cp); DESCRIPTION Converts the Internet '.' notation address specified by 'cp' to an Internet address and returns the network portion of the address. inet_ntoa SYNOPSIS #include <sys/types.h> #include <sys/socket.h> #include <netinet/in.h> #include <arpa/inet.h> char *inet_ntoa(struct in_addr in); DESCRIPTION Converts the Internet address specified by 'in' to an Internet '.' notation ASCIIZ string representing the address. Notes String is STATIC and will be overwritten with each call. setpwent SYNOPSIS #include <pwd.h> void setpwent(void); DESCRIPTION setpwent opens and rewinds the local password file. This call is primarily useful for resetting the password file to the first entry in preparation for calls to getpwent. getpwent SYNOPSIS #include <pwd.h> struct passwd *getpwent(void); DESCRIPTION getpwent reads the next entry in the local password file, opening the file if necessary. The return value is a pointer to a structure containing the broken-out fields of an entry from the password information file with the structure definition is as follows: struct passwd { char *pw_name; char *pw_passwd; int pw_uid; int pw_gid; int pw_quota; char *pw_comment; char *pw_gecos; char *pw_dir; char *pw_shell; }; pw_name Official username. pw_passwd Encrypted password for the user. pw_uid Userid for the user. pw_gid Unused at this time. pw_quota Unused at this time. pw_comment Unused at this time. pw_gecos Unused at this time. pw_dir Home directory for the user. pw_shell Unused at this time. Return Values getpwent returns: NULL on failure of EOF. See Also getpwuid, getpwnam, setpwent, getlogin, getuid getpwuid SYNOPSIS #include <pwd.h> struct passwd *getpwuid(int uid); DESCRIPTION getpwuid searches the password file sequentially for a pw_uid matching that specified by the uid parameter. When a match is found, the corresponding passwd entry is returned. Notes The passwd structure is defined in the description for getpwent. Return Values getpwuid returns: NULL on failure. getpwnam SYNOPSIS #include <pwd.h> struct passwd *getpwnam(char *name); DESCRIPTION getpwuid searches the password file sequentially for a pw_name matching that specified by the name parameter. When a match is found, the corresponding passwd entry is returned. Notes The passwd structure is defined in the description for getpwent. Return Values getpwnam returns: Null on failure. getlogin SYNOPSIS #include <pwd.h> char *getlogin(void); DESCRIPTION getlogin returns the username of the current system user. Notes Value returned is STATIC and is updated by subsequent calls. getuid SYNOPSIS #include <pwd.h> int getuid(void); DESCRIPTION getuid returns the user id of the current system user. DESQview/X Extension Routines In order for an application to use the BSD 4.3 Socket Library, several extension routines are needed. These perform the functions of initializing and terminating the use of the DESQview/X Berkeley Socket Interface. In addition routines are provided to facilitate communication with the Network Manager as a daemon process - see the Network Daemons Programming Reference for additional details and extension routines. so_init SYNOPSIS #include <sys\socket.h> int so_init(void); DESCRIPTION so_init is an extension call that initializes the DESQview/X Socket Interface and returns the availability of socket resources. Notes DESQview/X extension call. Return Values so_init returns 1 on success, 0 on failure. so_exit SYNOPSIS #include <sys\socket.h> void so_exit(void); DESCRIPTION Uninitializes the socket interface for the DESQview/X process. Notes DESQview/X extension call. so_setupdaemon SYNOPSIS #include <sys\socket.h> void so_setupdaemon(char *name); DESCRIPTION The so_setupdaemon call allows a DESQview/X application to assume the identity of a network daemon. The 'name' parameter refers to a valid entry in the local SERVICES file. Following the call, the application can then issue so_daemon calls to check for connections/datagrams--see the section Network Daemons Programming Reference for details. Notes DESQview/X extension call. getpwvar SYNOPSIS #include <pwd.h> char *getpwvar(char *key, char *var); DESCRIPTION getpwvar returns the ASCIIZ string describing the value indicated by parameters var and key. The key parameter indicates the key into the password information file and usually indicates a username. The var parameter is the variable that has been defined in the password information file to hold the value. Notes: DESQview/X extension call.